feat(windows): wrap .wolf hook commands in wscript+VBS to hide console flash - #42

Thanks @mann1x and @Mizuho0329. Your Windows wrapper proposal is credited; it has not been included, and console-flash validation remains open.

Closing this — and the validation you asked for is the reason. It says the wrapper in this PR cannot ship, and it also says the goal is achievable by other means. Both halves are measured, on two independent hosts.

The wrapper deadlocks every hook

hook-runner.vbs is built on WScript.Shell.Run, which gives the child a fresh console instead of the parent's pipes. Claude Code delivers the hook payload on stdin and reads the reply from stdout — as the comment at the top of src/cli/hook-manifest.ts notes for a related reason — so node waits forever on a stdin that never reaches EOF.

Measured identically on GitHub windows-latest (Server 2025) and on a Windows 10 Pro desktop:

So it does not merely lose output: it hangs until Claude Code's per-hook timeout, on every tool call. That is worse than the flash it removes, and it is why this should not be merged.

To be fair to the approach, the hiding part works. The same VBS, changed only from SW_HIDE to SW_SHOWNORMAL, showed 1 window against 0. The defect is exclusively in the stdio path.

What actually causes the flash

Not running node — console allocation. A parent process with no console of its own forces a console-subsystem child to allocate one, and that console is visible. Where the parent already owns a console, the child attaches to it and nothing appears.

Measured on the Win10 desktop, interactive session:

That last row is worth pausing on before anyone spends effort here: in the shape Claude Code actually uses, from a terminal, there is no flash to fix. It appears when whatever spawns the hook has no console of its own — a GUI-launched parent, an extension host, a service. So this affects some users' setups and not others, which probably explains why it has been hard to pin down.

A launcher that does work

The requirement is not "hide a window". It is: allocate no visible console, inherit the parent's std handles rather than replace them, and propagate the exit code. That means CreateProcess from a /target:winexe binary with both CREATE_NO_WINDOW and STARTF_USESTDHANDLES set to the parent's own GetStdHandle values, plus bInheritHandles.

Both halves are load-bearing. My first attempt used .NET's ProcessStartInfo with CreateNoWindow = true and no redirection, on the assumption that "no redirection" means "inherit the parent's handles". It hung exactly like the VBS — .NET sets STARTF_USESTDHANDLES only when it is redirecting, so CREATE_NO_WINDOW allocated a console and the child took its handles. Same defect, different costume.

With both flags, on the same desktop session as the table above:

Flash gone, hook contract intact.

The honest cost, and the options

This needs a native binary — roughly 4 KB — which is a real change in what an npm package contains, and you may reasonably decline on that alone. The options, with what each actually costs:

1. Ship a prebuilt .exe. Simplest at runtime. Costs: an unreviewable binary in a JS package, antivirus false positives on an unsigned launcher that spawns processes, code-signing expectations, and a per-architecture story for arm64.
2. Compile at install time with the csc.exe that ships in C:\Windows\Microsoft.NET\Framework64\ — present on every Windows, no SDK. No binary in the repo or the tarball, and the source is reviewable. Costs: it can be blocked by lockdown policy or AV, npm --ignore-scripts skips postinstall entirely, and it needs a fallback path when compilation fails. Doing it from openwolf init/update rather than postinstall avoids the --ignore-scripts problem.
3. Fall back cleanly. Whichever of the above, buildHookCommand should emit today's bare node "<script>" whenever the launcher is absent, so a failed build or a blocked install degrades to current behaviour rather than to a broken hook. That is how I would gate it.
4. Do nothing here, and report it upstream instead. The spawner is the one that controls the creation flags, and it is the only party that knows whether it has a console. A CREATE_NO_WINDOW in Claude Code's hook spawn fixes this for every hook of every tool, with no binary anywhere. Given the bash -c row above, this is arguably the correct place for the fix, and it costs openwolf nothing.

My honest read is that (4) is the right first move and (2)+(3) is the only version of a local fix I would argue for. I am happy to open a separate PR for (2)+(3) if you want it, and equally happy for the answer to be no — the measurement is the part worth having either way.

Both scripts are self-contained and on fix/windows-console-flash-validated: scripts/validate-console-flash.ps1 characterises the spawn shapes, scripts/study-gui-launcher.ps1 builds the launcher and tests it. They must run from an interactive desktop session and refuse to draw a conclusion in a headless one, rather than reporting "no window appeared" — which is what a blind harness would otherwise call success. Each has a control that must raise a window before any invisibility claim is accepted; both of my own calibration mistakes during this work surfaced that way instead of as a wrong answer.

🤖 Generated with Claude Code

Closing per the measurement above: the wrapper as written hangs every hook, so there is nothing here to merge. The launcher alternative is a separate proposal if you want it — no obligation, and the upstream option costs you nothing.